<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xml:lang="en" xmlns="http://www.w3.org/1999/xhtml" lang="en"><head>

	
		<meta http-equiv="Content-type" content="text/html; charset=UTF-8">
		<meta http-equiv="Content-Language" content="en-us">

		<title>Django | Widgets | Django Documentation</title>

		<meta name="ROBOTS" content="ALL">
		<meta http-equiv="imagetoolbar" content="no">
		<meta name="MSSmartTagsPreventParsing" content="true">
		<meta name="Copyright" content="This site's design and contents Copyright (c) 2005  Lawrence Journal-World.">

		<meta name="keywords" content="Python, Django, framework, open-source">
		<meta name="description" content="Django is a high-level Python Web framework that encourages rapid development and clean, pragmatic design.">

		<link href="Django%20%7C%20Widgets%20%7C%20Django%20Documentation_files/base.css" rel="stylesheet" type="text/css" media="screen">
		<link href="Django%20%7C%20Widgets%20%7C%20Django%20Documentation_files/print.css" rel="stylesheet" type="text/css" media="print">
      
  
  <style type="text/css" media="screen">
    #docs-search {
      color: #000;
      float: right;
    }
    #docs-search form {
      font-size: 92%;
      margin: 0;
      padding: 1em 1em 0;
      white-space: nowrap;
    }
    form.search ul {
      list-style: none;
      margin: 0;
      padding: 0;
    }
    form.search li {
      display: inline;
      padding-right: 1em;
    }
    form.search .query {
      width: 18em;
    }
  </style>
  <link rel="stylesheet" href="Django%20%7C%20Widgets%20%7C%20Django%20Documentation_files/pygments.css" type="text/css">

	</head><body id="documentation" class="default">

	<div id="container">
		<div id="header">
			<h1 id="logo"><a href="http://www.djangoproject.com/"><img src="Django%20%7C%20Widgets%20%7C%20Django%20Documentation_files/hdr_logo.gif" alt="Django"></a></h1>
			<ul id="nav-global">
				<li id="nav-homepage"><a href="http://www.djangoproject.com/">Home</a></li>
				<li id="nav-download"><a href="http://www.djangoproject.com/download/">Download</a></li>
				<li id="nav-documentation"><a href="http://docs.djangoproject.com/">Documentation</a></li>
				<li id="nav-weblog"><a href="http://www.djangoproject.com/weblog/">Weblog</a></li>
				<li id="nav-community"><a href="http://www.djangoproject.com/community/">Community</a></li>
				<li id="nav-code"><a href="http://code.djangoproject.com/">Code</a></li>
			</ul>
		</div>
		<!-- END Header -->
		<div id="billboard">
  <h2><a href="http://docs.djangoproject.com/en/1.0/">Django documentation</a></h2>
</div>
		<div id="columnwrap">
			
		<div id="content-main">
		


  <h2 class="deck">
  
    This document describes Django version 1.0. For development documentation, 
    <a href="http://docs.djangoproject.com/en/dev/ref/forms/widgets/">go here</a>.
  
  </h2>
  <div class="section" id="s-module-django.forms.widgets">
<span id="s-ref-forms-widgets"></span><span id="module-django.forms.widgets"></span><span id="ref-forms-widgets"></span><h1>Widgets<a class="headerlink" href="#module-django.forms.widgets" title="Permalink to this headline">¶</a></h1>
<p>A widget is Django’s representation of a HTML input element. The widget
handles the rendering of the HTML, and the extraction of data from a GET/POST
dictionary that corresponds to the widget.</p>
<p>Django provides a representation of all the basic HTML widgets, plus some
commonly used groups of widgets:</p>
<dl class="class">
<dt id="django.forms.TextInput">
<!--[django.forms.TextInput]-->class <tt class="descname">TextInput</tt><a class="headerlink" href="#django.forms.TextInput" title="Permalink to this definition">¶</a></dt>
<dd>Text input: <tt class="docutils literal"><span class="pre">&lt;input</span> <span class="pre">type='text'</span> <span class="pre">...&gt;</span></tt></dd></dl>

<dl class="class">
<dt id="django.forms.PasswordInput">
<!--[django.forms.PasswordInput]-->class <tt class="descname">PasswordInput</tt><a class="headerlink" href="#django.forms.PasswordInput" title="Permalink to this definition">¶</a></dt>
<dd>Password input: <tt class="docutils literal"><span class="pre">&lt;input</span> <span class="pre">type='password'</span> <span class="pre">...&gt;</span></tt></dd></dl>

<dl class="class">
<dt id="django.forms.HiddenInput">
<!--[django.forms.HiddenInput]-->class <tt class="descname">HiddenInput</tt><a class="headerlink" href="#django.forms.HiddenInput" title="Permalink to this definition">¶</a></dt>
<dd>Hidden input: <tt class="docutils literal"><span class="pre">&lt;input</span> <span class="pre">type='hidden'</span> <span class="pre">...&gt;</span></tt></dd></dl>

<dl class="class">
<dt id="django.forms.MultipleHiddenInput">
<!--[django.forms.MultipleHiddenInput]-->class <tt class="descname">MultipleHiddenInput</tt><a class="headerlink" href="#django.forms.MultipleHiddenInput" title="Permalink to this definition">¶</a></dt>
<dd>Multiple <tt class="docutils literal"><span class="pre">&lt;input</span> <span class="pre">type='hidden'</span> <span class="pre">...&gt;</span></tt> widgets.</dd></dl>

<dl class="class">
<dt id="django.forms.FileInput">
<!--[django.forms.FileInput]-->class <tt class="descname">FileInput</tt><a class="headerlink" href="#django.forms.FileInput" title="Permalink to this definition">¶</a></dt>
<dd>File upload input: <tt class="docutils literal"><span class="pre">&lt;input</span> <span class="pre">type='file'</span> <span class="pre">...&gt;</span></tt></dd></dl>

<dl class="class">
<dt id="django.forms.DateTimeInput">
<!--[django.forms.DateTimeInput]-->class <tt class="descname">DateTimeInput</tt><a class="headerlink" href="#django.forms.DateTimeInput" title="Permalink to this definition">¶</a></dt>
<dd><div class="versionadded">
<span class="title">New in Django 1.0:</span> <a class="reference external" href="http://docs.djangoproject.com/en/1.0/releases/1.0/#releases-1-0"><em>Please, see the release notes</em></a></div>
<p>Date/time input as a simple text box: <tt class="docutils literal"><span class="pre">&lt;input</span> <span class="pre">type='text'</span> <span class="pre">...&gt;</span></tt></p>
</dd></dl>

<dl class="class">
<dt id="django.forms.Textarea">
<!--[django.forms.Textarea]-->class <tt class="descname">Textarea</tt><a class="headerlink" href="#django.forms.Textarea" title="Permalink to this definition">¶</a></dt>
<dd>Text area: <tt class="docutils literal"><span class="pre">&lt;textarea&gt;...&lt;/textarea&gt;</span></tt></dd></dl>

<dl class="class">
<dt id="django.forms.CheckboxInput">
<!--[django.forms.CheckboxInput]-->class <tt class="descname">CheckboxInput</tt><a class="headerlink" href="#django.forms.CheckboxInput" title="Permalink to this definition">¶</a></dt>
<dd>Checkbox: <tt class="docutils literal"><span class="pre">&lt;input</span> <span class="pre">type='checkbox'</span> <span class="pre">...&gt;</span></tt></dd></dl>

<dl class="class">
<dt id="django.forms.Select">
<!--[django.forms.Select]-->class <tt class="descname">Select</tt><a class="headerlink" href="#django.forms.Select" title="Permalink to this definition">¶</a></dt>
<dd><p>Select widget: <tt class="docutils literal"><span class="pre">&lt;select&gt;&lt;option</span> <span class="pre">...&gt;...&lt;/select&gt;</span></tt></p>
<p>Requires that your field provides <tt class="xref docutils literal"><span class="pre">choices</span></tt>.</p>
</dd></dl>

<dl class="class">
<dt id="django.forms.NullBooleanSelect">
<!--[django.forms.NullBooleanSelect]-->class <tt class="descname">NullBooleanSelect</tt><a class="headerlink" href="#django.forms.NullBooleanSelect" title="Permalink to this definition">¶</a></dt>
<dd>Select widget with options ‘Unknown’, ‘Yes’ and ‘No’</dd></dl>

<dl class="class">
<dt id="django.forms.SelectMultiple">
<!--[django.forms.SelectMultiple]-->class <tt class="descname">SelectMultiple</tt><a class="headerlink" href="#django.forms.SelectMultiple" title="Permalink to this definition">¶</a></dt>
<dd><p>Select widget allowing multiple selection: <tt class="docutils literal"><span class="pre">&lt;select</span>
<span class="pre">multiple='multiple'&gt;...&lt;/select&gt;</span></tt></p>
<p>Requires that your field provides <tt class="xref docutils literal"><span class="pre">choices</span></tt>.</p>
</dd></dl>

<dl class="class">
<dt id="django.forms.RadioSelect">
<!--[django.forms.RadioSelect]-->class <tt class="descname">RadioSelect</tt><a class="headerlink" href="#django.forms.RadioSelect" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of radio buttons:</p>
<div class="highlight-html"><pre>&lt;ul&gt;
  &lt;li&gt;&lt;input type='radio' ...&gt;&lt;/li&gt;
  ...
&lt;/ul&gt;</pre>
</div>
<p>Requires that your field provides <tt class="xref docutils literal"><span class="pre">choices</span></tt>.</p>
</dd></dl>

<dl class="class">
<dt id="django.forms.CheckboxSelectMultiple">
<!--[django.forms.CheckboxSelectMultiple]-->class <tt class="descname">CheckboxSelectMultiple</tt><a class="headerlink" href="#django.forms.CheckboxSelectMultiple" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of checkboxes:</p>
<div class="highlight-html"><pre>&lt;ul&gt;
  &lt;li&gt;&lt;input type='checkbox' ...&gt;&lt;/li&gt;
  ...
&lt;/ul&gt;</pre>
</div>
</dd></dl>

<dl class="class">
<dt id="django.forms.MultiWidget">
<!--[django.forms.MultiWidget]-->class <tt class="descname">MultiWidget</tt><a class="headerlink" href="#django.forms.MultiWidget" title="Permalink to this definition">¶</a></dt>
<dd>Wrapper around multiple other widgets</dd></dl>

<dl class="class">
<dt id="django.forms.SplitDateTimeWidget">
<!--[django.forms.SplitDateTimeWidget]-->class <tt class="descname">SplitDateTimeWidget</tt><a class="headerlink" href="#django.forms.SplitDateTimeWidget" title="Permalink to this definition">¶</a></dt>
<dd>Wrapper around two <tt class="docutils literal"><span class="pre">TextInput</span></tt> widgets: one for the date, and one for the
time.</dd></dl>

<div class="section" id="s-specifying-widgets">
<span id="specifying-widgets"></span><h2>Specifying widgets<a class="headerlink" href="#specifying-widgets" title="Permalink to this headline">¶</a></h2>
<dl class="attribute">
<dt id="django.forms.Form.widget">
<!--[django.forms.Form.widget]--><tt class="descclassname">Form.</tt><tt class="descname">widget</tt><a class="headerlink" href="#django.forms.Form.widget" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>Whenever you specify a field on a form, Django will use a default widget
that is appropriate to the type of data that is to be displayed. To find
which widget is used on which field, see the documentation for the
built-in Field classes.</p>
<p>However, if you want to use a different widget for a field, you can -
just use the 'widget' argument on the field definition. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">from</span> <span class="nn">django</span> <span class="k">import</span> <span class="n">forms</span>

<span class="k">class</span> <span class="nc">CommentForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
    <span class="n">name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
    <span class="n">url</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">URLField</span><span class="p">()</span>
    <span class="n">comment</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">widget</span><span class="o">=</span><span class="n">forms</span><span class="o">.</span><span class="n">Textarea</span><span class="p">)</span>
</pre></div>
</div>
<p>This would specify a form with a comment that uses a larger Textarea widget,
rather than the default TextInput widget.</p>
</div>
<div class="section" id="s-customizing-widget-instances">
<span id="customizing-widget-instances"></span><h2>Customizing widget instances<a class="headerlink" href="#customizing-widget-instances" title="Permalink to this headline">¶</a></h2>
<p>When Django renders a widget as HTML, it only renders the bare minimum
HTML - Django doesn't add a class definition, or any other widget-specific
attributes. This means that all 'TextInput' widgets will appear the same
on your web page.</p>
<p>If you want to make one widget look different to another, you need to
specify additional attributes for each widget. When you specify a
widget, you can provide a list of attributes that will be added to the
rendered HTML for the widget.</p>
<p>For example, take the following simple form:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">CommentForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
    <span class="n">name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
    <span class="n">url</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">URLField</span><span class="p">()</span>
    <span class="n">comment</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
</pre></div>
</div>
<p>This form will include three default TextInput widgets, with default rendering -
no CSS class, no extra attributes. This means that the input boxes provided for
each widget will be rendered exactly the same:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">CommentForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">as_table</span><span class="p">()</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Name:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="name" /&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Url:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="url"/&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Comment:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="comment" /&gt;&lt;/td&gt;&lt;/tr&gt;</span>
</pre></div>
</div>
<p>On a real web page, you probably don't want every widget to look the same. You
might want a larger input element for the comment, and you might want the 'name'
widget to have some special CSS class. To do this, you use the <tt class="docutils literal"><span class="pre">attrs</span></tt>
argument when creating the widget:</p>
<dl class="attribute">
<dt id="django.forms.Widget.attrs">
<!--[django.forms.Widget.attrs]--><tt class="descclassname">Widget.</tt><tt class="descname">attrs</tt><a class="headerlink" href="#django.forms.Widget.attrs" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">CommentForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
    <span class="n">name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span>
                <span class="n">widget</span><span class="o">=</span><span class="n">forms</span><span class="o">.</span><span class="n">TextInput</span><span class="p">(</span><span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s">'class'</span><span class="p">:</span><span class="s">'special'</span><span class="p">}))</span>
    <span class="n">url</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">URLField</span><span class="p">()</span>
    <span class="n">comment</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span>
               <span class="n">widget</span><span class="o">=</span><span class="n">forms</span><span class="o">.</span><span class="n">TextInput</span><span class="p">(</span><span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s">'size'</span><span class="p">:</span><span class="s">'40'</span><span class="p">}))</span>
</pre></div>
</div>
<p>Django will then include the extra attributes in the rendered output:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">CommentForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">as_table</span><span class="p">()</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Name:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="name" class="special"/&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Url:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="url"/&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Comment:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="comment" size="40"/&gt;&lt;/td&gt;&lt;/tr&gt;</span>
</pre></div>
</div>
</div>
</div>



<div id="content-secondary">
  <h2 id="comments">Questions/Feedback</h2>
  <p>Having trouble? We'd like to help!</p>
  <ul>
    <li>
      Try the <a href="http://docs.djangoproject.com/en/dev/faq/">FAQ</a> — it's got answers to many common
      questions.
    </li>
    <li>
      Search for information in the <a href="http://groups.google.com/group/django-users/">archives of the
      django-users mailing list</a>, or <a href="http://groups.google.com/group/django-users/">post a question</a>.
    </li>
    <li>
      Ask a question in the <a href="irc://irc.freenode.net/">#django IRC
      channel</a>, or search the <a href="http://oebfare.com/logger/django/">IRC
      logs</a> to see if its been asked before.
    </li>
    <li>
      If you notice errors with this documentation, please <a href="http://code.djangoproject.com/simpleticket?component=Documentation">
      open a ticket</a> and let us know! Please only use the ticket tracker for
      criticisms and improvements on the docs. For tech support, use the
      resources above.
    </li>
  </ul>
</div>

		</div>
		<!-- END #content-main -->
		<div id="content-related" class="sidebar">
		
  
    <h2>Contents</h2>
    
      <ul>
<li><a class="reference external" href="">Widgets</a><ul>
<li><a class="reference external" href="#specifying-widgets">Specifying widgets</a></li>
<li><a class="reference external" href="#customizing-widget-instances">Customizing widget instances</a></li>
</ul>
</li>
</ul>

    
  
  
  
    <h2>Search</h2>
    
    <form action="/en/1.0/search/" id="search" class="search">
  <div>
    <input name="cx" value="009763561546736975936:e88ek0eurf4" type="hidden">
    <input name="cof" value="FORID:11" type="hidden">
    <input name="ie" value="UTF-8" type="hidden">
    <input name="hl" value="" type="hidden">
    <input style="background: rgb(255, 255, 255) url(http://www.google.com/coop/intl/en/images/google_custom_search_watermark.gif) no-repeat scroll left center; -moz-background-clip: -moz-initial; -moz-background-origin: -moz-initial; -moz-background-inline-policy: -moz-initial;" id="id_search_q" class="query" name="q" type="text">
    <input name="sa" class="submit" value="Search" type="submit">
    <ul>
<li><label for="id_search_as_q_0"><input checked="checked" id="id_search_as_q_0" value="more:dev_docs" name="as_q" type="radio"> Latest</label></li>
<li><label for="id_search_as_q_1"><input id="id_search_as_q_1" value="more:1.0_docs" name="as_q" type="radio"> 1.0</label></li>
<li><label for="id_search_as_q_2"><input id="id_search_as_q_2" value="more:0.96_docs" name="as_q" type="radio"> 0.96</label></li>
<li><label for="id_search_as_q_3"><input id="id_search_as_q_3" value="more:all_docs" name="as_q" type="radio"> All</label></li>
</ul>
  </div>
</form>
<script type="text/javascript" src="Django%20%7C%20Widgets%20%7C%20Django%20Documentation_files/brand.html"></script>
  
  
  
    <h2>Browse</h2>
    <ul>
      
        
          <li>Prev: <a href="http://docs.djangoproject.com/en/1.0/ref/forms/fields/">Form fields</a></li>
        
        
          <li>Next: <a href="http://docs.djangoproject.com/en/1.0/ref/forms/validation/">Form and field validation</a></li>
        
        <li><a href="http://docs.djangoproject.com/en/1.0/contents/">Table of contents</a></li>
        
          <li><a href="http://docs.djangoproject.com/en/1.0/genindex/">General Index</a></li>
        
          <li><a href="http://docs.djangoproject.com/en/1.0/modindex/">Global Module Index</a></li>
        
      
    </ul>
  
  
  
    <h2>You are here:</h2>
    <ul>
      
        <li>
          <a href="http://docs.djangoproject.com/en/1.0/">Django 1.0 documentation</a>
          
            <ul><li><a href="http://docs.djangoproject.com/en/1.0/ref/">API Reference</a>
          
            <ul><li><a href="http://docs.djangoproject.com/en/1.0/ref/forms/">Forms</a>
          
          <ul><li>Widgets</li></ul>
          </li></ul></li></ul>
        </li>
      
    </ul>
  
  
  
    <h3>Last update:</h3>
    <div>May 23, 2009, 8:15 a.m. (<a href="http://www.timeanddate.com/worldclock/city.html?n=64">CDT</a>)</div>
  

		</div>
		<!-- END #content-related -->

		</div>
		<!-- END #content -->
		<div id="footer">
			<p>© 2005-2009 <a href="http://www.djangoproject.com/foundation/">Django Software Foundation</a> unless otherwise noted. Django is a registered trademark of the Django Software Foundation. 
			Hosting graciously provided by <a href="http://mediatemple.net/">
			<img style="vertical-align: middle; position: relative; top: -1px;" src="Django%20%7C%20Widgets%20%7C%20Django%20Documentation_files/mt.png" alt="media temple"></a>
			</p>
		</div>
		<!-- END #footer -->
	</div>
	<!-- END #container -->
	</body></html>